/**
 * InventoryApp.kt
 */
/**
 * 文件级注解和包声明
 * 作用：整个文件启用Material3的实验性API（因为CenterAlignedTopAppBar等组件在Material3中可能还处于实验阶段）
 * 注意：使用@OptIn需要确保调用方也处理了API实验性状态
 */
@file:OptIn(ExperimentalMaterial3Api::class)
package com.example.inventoryapp

import androidx.compose.material.icons.Icons
import androidx.compose.material.icons.automirrored.filled.ArrowBack
import androidx.compose.material3.CenterAlignedTopAppBar
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.Icon
import androidx.compose.material3.IconButton
import androidx.compose.material3.Text
import androidx.compose.material3.TopAppBarScrollBehavior
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import androidx.compose.ui.res.stringResource
import androidx.navigation.NavHostController
import androidx.navigation.compose.rememberNavController
import com.example.inventoryapp.R.string
import com.example.inventoryapp.ui.navigation.InventoryNavHost

/**
 * 应用入口组件 - InventoryApp
 * 功能：作为整个应用的根组件
 * 参数：
 * navController: NavHostController- 导航控制器，默认通过rememberNavController()创建
 * 内部逻辑：
 * 调用InventoryNavHost组件并传入导航控制器
 * InventoryNavHost是实际管理导航图的组件（在其他文件中定义）
 */
@Composable
fun InventoryApp(navController: NavHostController = rememberNavController()) {
    InventoryNavHost(navController = navController)
}

/**
 * 自定义顶部应用栏 - InventoryTopAppBar
 * title: String:
 * 应用栏中央显示的标题文本
 * 通常是当前屏幕的名称或功能描述
 * canNavigateBack: Boolean:
 * 控制是否显示返回按钮
 * 通常在导航栈中有上一个目标时设为 true
 * modifier: Modifier = Modifier:
 * 允许自定义应用栏的样式和布局
 * 默认值为空修饰符
 * scrollBehavior: TopAppBarScrollBehavior? = null:
 * 可选参数，控制应用栏在滚动时的行为
 * 如滚动时隐藏/显示、改变高度等效果
 * navigateUp: () -> Unit = {}:
 * 返回按钮点击时的回调函数
 * 通常用于执行导航回退操作
 * 组件实现细节
 * CenterAlignedTopAppBar:
 * Material3 提供的居中标题应用栏组件
 * 替代了传统的 TopAppBar
 * navigationIcon:
 * 左侧区域的自定义内容
 * 使用条件判断 if (canNavigateBack)决定是否显示返回按钮
 * IconButton:
 * 可点击的图标按钮
 * onClick绑定到 navigateUp回调
 * Icon:
 * 显示返回箭头图标
 * Icons.AutoMirrored.Filled.ArrowBack:
 * 自动镜像的图标（支持从右到左的语言）
 * 在RTL布局中自动翻转方向
 * contentDescription:
 * 无障碍描述文本
 * 使用 stringResource从资源文件中获取
 */
@Composable
fun InventoryTopAppBar(
    title: String,                                      // 标题文本
    canNavigateBack: Boolean,                           // 是否显示返回按钮
    modifier: Modifier = Modifier,                      // 样式修饰符
    scrollBehavior: TopAppBarScrollBehavior? = null,    // 滚动行为配置
    navigateUp: () -> Unit = {}                         // 返回按钮点击回调
) {
    CenterAlignedTopAppBar(
        title = { Text(title) },        // 居中标题
        modifier = modifier,
        scrollBehavior = scrollBehavior,
        navigationIcon = {                      // 导航图标（左侧）
            if (canNavigateBack) {              // 根据条件显示返回按钮
                IconButton(onClick = navigateUp) {
                    Icon(
                        imageVector = Icons.AutoMirrored.Filled.ArrowBack,  // 自动镜像的返回图标
                        contentDescription = stringResource(string.back_button)         // 无障碍描述
                    )
                }
            }
        }
    )
}

/**
 * 关键设计特点
 * 导航解耦:
 * 入口组件 InventoryApp只负责初始化导航控制器
 * 实际路由逻辑在 InventoryNavHost中实现
 * 可复用组件:
 * InventoryTopAppBar封装了通用顶部栏逻辑
 * 通过参数控制返回按钮的显示和行为
 * 可在多个屏幕中复用
 * 国际化支持:
 * 使用 stringResource获取本地化字符串
 * 图标自动镜像支持RTL布局
 * 无障碍设计:
 * 为图标提供内容描述
 * 确保屏幕阅读器能正确识别
 * 灵活配置:
 * 通过参数控制各种行为
 * 支持自定义修饰符和滚动行为
 *
 * 总结：
 * 这个文件提供了：
 *
 * 应用入口点 (InventoryApp)
 * 可复用的顶部导航栏组件 (InventoryTopAppBar)
 * 导航系统的初始化
 * 一致的用户界面元素
 */